home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 1 / Amiga Tools.iso / egs-tools / egs_demo-version / egs_devels / doc / egsrequest.doc < prev    next >
Text File  |  1994-06-06  |  9KB  |  390 lines
  1. /*
  2. *  $
  3. *  $ FILE     : egsrequest.doc
  4. *  $ VERSION  : 1
  5. *  $ REVISION : 1
  6. *  $ DATE     : 08-Feb-93 10:06
  7. *  $
  8. *  $ Author   : mvk
  9. *  $
  10. *
  11. *
  12. * (c) Copyright 1990/93 VIONA Development
  13. *     All Rights Reserved
  14. *
  15. */
  16.  
  17. egsrequest.library/ER_CancelRequest
  18. egsrequest.library/ER_ChangeRequestPos
  19. egsrequest.library/ER_ChangeRequestSize
  20. egsrequest.library/ER_CreateFileReq
  21. egsrequest.library/ER_CreateReqContext
  22. egsrequest.library/ER_CreateSimpleRequest
  23. egsrequest.library/ER_DeleteReqContext
  24. egsrequest.library/ER_DeleteRequest
  25. egsrequest.library/ER_DoRequest
  26. egsrequest.library/ER_FindRequest
  27. egsrequest.library/ER_IterateRequest
  28. egsrequest.library/ER_OpenRequest
  29. egsrequest.library/ER_PutValuesInFileReq
  30.  
  31. egsrequest.library/ER_CancelRequest
  32. NAME
  33.   ER_CancelRequest    cancels pending request
  34.  
  35. SYNOPSIS
  36.   ER_CancelRequest(req);
  37.            A0
  38.  
  39.   ER_RequestPtr   req;
  40.  
  41. FUNCTION
  42.   Cancels a pending request. The associated window is closed. The requester
  43.   structure is NOT freed. If the requester is not currently in use this is
  44.   a no operation.
  45.  
  46. INPUTS
  47.   req    : request to be canceled
  48.  
  49. RETURNS
  50.  
  51.  
  52.  
  53. egsrequest.library/ER_ChangeRequestPos
  54. NAME
  55.   ER_ChangeRequestPos   Moves a requester
  56.  
  57. SYNOPSIS
  58.   ER_ChangeRequestPos(req, x, y);
  59.               A0   D0 D1
  60.  
  61.   ER_RequestPtr    req;
  62.   WORD             x,y;
  63.  
  64. FUNCTION
  65.   Moves a requester to the absolute location x/y. If the requester is not
  66.   currently open, it will open up on this position the next time it is
  67.   used.
  68.  
  69. INPUTS
  70.   req    : requester to be moved
  71.   x,y    : absolute destination location
  72.  
  73. RETURNS
  74.  
  75.  
  76.  
  77. egsrequest.library/ER_ChangeRequestSize
  78. NAME
  79.   ER_ChangeRequestSize   Resizes a requester
  80.  
  81. SYNOPSIS
  82.   ER_ChangeRequestSize(req, w, h);
  83.                A0   D0 D1
  84.  
  85.   ER_RequestPtr   req;
  86.   WORD            x,y;
  87.  
  88. FUNCTION
  89.   Changes the size of a requester to the given dimensions. The values are
  90.   clipped to the maximum and minimum requester size, so no harm can be
  91.   done. If the requester is not currently open, it will open up in this
  92.   size the next time it is used.
  93.  
  94. INPUTS
  95.   req      : requester to be resized
  96.   w,h      : new width and height
  97.  
  98. RETURNS
  99.  
  100.  
  101.  
  102. egsrequest.library/ER_CreateFileReq
  103. NAME
  104.   ER_CreateFileReq    create an filerequester
  105.  
  106. SYNOPSIS
  107.   freq = ER_CreateFileReq(con);
  108.   D0                      A0
  109.  
  110.   ER_FileRequestPtr    freq;
  111.   ER_ReqContextPtr     con;
  112.  
  113. FUNCTION
  114.   Creates a filerequester, associated to the given requester context, or to
  115.   none if 'con' equals NULL. The requester is not immediately opened. You can
  116.   open it using 'ER_OpenRequest' or 'ER_DoRequest'. If the request is finished
  117.   you find the results in the appropriate structure elements. (see the includes
  118.   for more information)
  119.   You may reuse a file requester as often as you like.
  120.  
  121. INPUTS
  122.   con    : Requester context, in which the filerequest shall become a member.
  123.        If NULL, the requester will be a free citizen.
  124.  
  125. RETURNS
  126.   freq   : a fully initialized file requester
  127.  
  128.  
  129.  
  130. egsrequest.library/ER_CreateReqContext
  131. NAME
  132.   ER_CreateReqContext   create a requester context
  133.  
  134. SYNOPSIS
  135.   con = ER_CreateReqContext();
  136.   D0
  137.  
  138.   ER_ReqContextPtr  con;
  139.  
  140. FUNCTION
  141.   Creates a requester context. You can use it, to keep track of your requester
  142.   and make life much easier.
  143.  
  144. INPUTS
  145.  
  146. RETURNS
  147.   con   : an initialized requster context
  148.  
  149.  
  150.  
  151. egsrequest.library/ER_CreateSimpleRequest
  152. NAME
  153.   ER_CreateSimpleRequest   creates a simple requester
  154.  
  155. SYNOPSIS
  156.   sreq = ER_CreateSimpleRequest(con, texts, selects);
  157.   D0                            A0   A1     A2
  158.  
  159.   ER_SimpleRequestPtr  sreq;
  160.   ER_ReqContext        con;
  161.   char                *text;
  162.   char                *selects;
  163.  
  164. FUNCTION
  165.   Creates a simple requester. Such a requester is build out of an information
  166.   field and a number of action gadgets. The text and the names of the gadgets
  167.   are defined in strings. Lines/Gadgets can be separated by "|". After the
  168.   request is finished, the number of the chosen gadget is found in the
  169.   requester structure. The gadgets are numbered from left to right, starting
  170.   with 0 for the first gadget.
  171.   The requester is not instantly opened. It can be displayed using
  172.   'ER_DoRequest' or 'ER_OpenRequest'.
  173.   You may reuse a simple requester as often as you like.
  174.  
  175. EXAMPLE
  176.   An call of
  177.  
  178.   ... ER_CreateSimpleRequest(NULL,"This is not|a known file|format",
  179.                   "Retry|Define|Cancel");
  180.  
  181.   will result in a requester shaped like this:
  182.  
  183.     ###---------------------###-###
  184.     ###---------------------###-###
  185.     |+---------------------------+|
  186.     ||        This is not        ||
  187.     ||       a known file        ||
  188.     ||          format.          ||
  189.     |+---------------------------+|
  190.     |+-------++--------++--------+|
  191.     || Retry || Define || Cancel ||
  192.     |+-------++--------++--------+|
  193.     +-----------------------------#
  194.  
  195. INPUTS
  196.   con    : Requester context, in which the simple request shall become a member.
  197.        If NULL, the requester will be a free citizen.
  198.   texts  : contents of the body text.
  199.   selects: names of the gadgets
  200.  
  201. RETURNS
  202.   sreq   : a fully initialized simple request structure
  203.  
  204.  
  205.  
  206. egsrequest.library/ER_DeleteReqContext
  207. NAME
  208.   ER_DeleteReqContext   delete a requester context
  209.  
  210. SYNOPSIS
  211.   ER_DeleteReqContext(con)
  212.               A0
  213.  
  214.   ER_ReqContextPtr   con;
  215.  
  216. FUNCTION
  217.   Deletes a requester context AND ALL associated requesters. Pending requesters
  218.   are canceled, so make sure not to wait for them to finish or to reuse them.
  219.   You can keep track of your requesters in a requester context, and use this
  220.   function to delete them all in case of fire or exit.
  221.  
  222. INPUTS
  223.   con      : the requester context to be deleted
  224.  
  225. RETURNS
  226.  
  227.  
  228.  
  229.  
  230. egsrequest.library/ER_DeleteRequest
  231. NAME
  232.   ER_DeleteRequest    delete a requester
  233.  
  234. SYNOPSIS
  235.   ER_DeleteRequest(req)
  236.            A0
  237.  
  238.   ER_RequestPtr  req;
  239.  
  240. FUNCTION
  241.   Deletes a requester (any kind). If the request is still pending, it is
  242.   canceled and the window closed.
  243.  
  244. INPUTS
  245.   req     : the requester to be deleted
  246.  
  247. RETURNS
  248.  
  249.  
  250.  
  251. egsrequest.library/ER_DoRequest
  252. NAME
  253.   ER_DoRequest    open and start a request
  254.  
  255. SYNOPSIS
  256.   done = ER_DoRequest(req)
  257.   D0                  A0
  258.  
  259.   BOOL           done;
  260.   ER_RequestPtr  req;
  261.  
  262. FUNCTION
  263.   Opens a request, and starts to handle it events. This call does only return
  264.   if the requester was not successfully opened, or after the request is
  265.   finished.
  266.  
  267. INPUTS
  268.   req     : requester to be requested
  269.  
  270. RETURNS
  271.   done    : true, if the request was successfull
  272.  
  273.  
  274.  
  275. egsrequest.library/ER_FindRequest
  276. NAME
  277.   ER_FindRequest    find a request in a context
  278.  
  279. SYNOPSIS
  280.   req = ER_FindRequest(con, msg)
  281.   D0                   A0   A1
  282.  
  283.   ER_RequestPtr      req;
  284.   ER_ReqContextPtr   con;
  285.   EI_EIntuiMsgPtr    msg;
  286.  
  287. FUNCTION
  288.   Searches in a request context for a requester, that fits to the message.
  289.   If none is found this call returns NULL. You can use this function to
  290.   easily determine for which requester (or none at all) the message was
  291.   send.
  292.  
  293. INPUTS
  294.   con       : a requester context, that may contain the requester
  295.   msg       : a message that might be for a requester
  296.  
  297. RETURNS
  298.   req       : the fitting requester or NULL if none fits
  299.  
  300.  
  301.  
  302. egsrequest.library/ER_IterateRequest
  303. NAME
  304.   ER_IterateRequest   iterates a requester
  305.  
  306. SYNOPSIS
  307.   notFinished = ER_IterateRequest(req, msg);
  308.   D0                              A0   A1
  309.  
  310.   BOOL            notFinished;
  311.   ER_RequestPtr   req;
  312.   EI_EIntuiMsgPtr msg;
  313.  
  314. FUNCTION
  315.   Iterates a requester according to an intui message. If it is called with
  316.   a NULL requester, or a message that does not fit to the requester, this
  317.   is a no operation. If the message terminates the requester (e.g 'OK') this
  318.   function will return false.
  319.  
  320. INPUTS
  321.   req         : a requester that should fit to the message
  322.   msg         : an intui message received through the main port
  323.  
  324. RETURNS
  325.   notFinished : false if the requester is terminated
  326.  
  327.  
  328.  
  329. egsrequest.library/ER_OpenRequest
  330. NAME
  331.   ER_OpenRequest    open a request an return
  332.  
  333. SYNOPSIS
  334.   success = ER_OpenRequest(req, win);
  335.   D0                       A0   A1
  336.  
  337.   BOOL             success;
  338.   ER_RequestPtr    req;
  339.   EI_WindowPtr     win;
  340.  
  341. FUNCTION
  342.   Opens a requester and returns immediately. If the requester could not
  343.   be opened (for any reasons) this call returns false. You have to iterate
  344.   the request by using 'ER_IterateRequest'. If you supply a window, the
  345.   requester will share its port and screen.
  346.   The requester is closed, if the iteration yields in a termination, or
  347.   a call to 'ER_CancelRequest'.
  348.   If the requester is allready open, this is a no operation.
  349.  
  350. INPUTS
  351.   req        : requester to be opened
  352.   win        : a window, to share its port and screen, or NULL for the
  353.            port and screen defined in the request structure
  354.  
  355. RETURNS
  356.   success    : true if the requester couldt be opened
  357.  
  358.  
  359.  
  360. egsrequest.library/ER_PutValuesInFileReq
  361. NAME
  362.   ER_PutValuesInFileReq    put values in file requester
  363.  
  364. SYNOPSIS
  365.   ER_PutValuesInFileReq(freq, name, path, pattern);
  366.             A0    A1    A2    A3
  367.  
  368.   ER_FileRequestPtr  freq;
  369.   char              *name, *path, *pattern;
  370.  
  371. FUNCTION
  372.   Changes the name, path and/or pattern values of a file requester. If the
  373.   requester is opened, the change takes place immediately, otherwise the
  374.   requester will pop up with the new values, the next time it is used.
  375.   NULL values for either parameter will not affect the original values.
  376.  
  377. INPUTS
  378.   freq     : the filerequester to be changed
  379.   name     : a new name string or NULL
  380.   path     : a new path string or NULL
  381.   pattern  : a new pattern string or NULL
  382.  
  383. RETURNS
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.